home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 18 / CU Amiga Magazine's Super CD-ROM 18 (1997)(EMAP Images)(GB)[!][issue 1998-01].iso / CUCD / Programming / ModemLink / AutoDocs / ModemLink.doc next >
Text File  |  1997-10-20  |  39KB  |  1,045 lines
  1.  
  2.  
  3. TABLE OF CONTENTS
  4.  
  5. modemlink.device/AbortIO
  6. modemlink.device/CMD_CLEAR
  7. modemlink.device/CMD_READ
  8. modemlink.device/CMD_WRITE
  9. modemlink.device/MLCMD_INIT
  10. modemlink.device/MLCMD_QUERY
  11. modemlink.device/MLCMD_READ
  12. modemlink.device/MLCMD_WRITE
  13. modemlink.device/ML_AllocPkt
  14. modemlink.device/ML_AnswerTagList
  15. modemlink.device/ML_DePacketizeData
  16. modemlink.device/ML_DialTagList
  17. modemlink.device/ML_EstablishTagList
  18. modemlink.device/ML_FreePkt
  19. modemlink.device/ML_FreePktList
  20. modemlink.device/ML_PacketDataSize
  21. modemlink.device/ML_PacketizeData
  22. modemlink.device/ML_SendModemCMDTagList
  23. modemlink.device/ML_Terminate
  24. modemlink.lib/ML_AbortIO (lib)
  25. modemlink.lib/ML_DoIO (lib)
  26. modemlink.lib/ML_SendIO (lib)
  27.  
  28.  
  29. modemlink.device/AbortIO                              modemlink.device/AbortIO
  30.  
  31.  
  32.    NAME
  33.        AbortIO -- abort an I/O request
  34.  
  35.    SYNOPSIS
  36.        AbortIO( IORequest )
  37.                 A1
  38.  
  39.        void AbortIO(struct IORequest * );
  40.  
  41.    FUNCTION
  42.        This is an exec.library call.
  43.  
  44.        This function attempts to abort a specified read or write request.
  45.        If the request being aborted is a WRITE request and is currently
  46.        active, the IO request will NOT be aborted and will be completed
  47.        as normal.  If the request is queued, it is painlessly removed.
  48.        The request will be returned in the same way any completed request
  49.        is.
  50.  
  51.        After AbortIO(), you must generally do a WaitIO().
  52.  
  53.    NOTE
  54.        This can only be called when using the modemlink.device.  If you are
  55.        using ModemLink.lib use ML_AbortIO() instead.  This is because exec
  56.        call to AbortIO expects to be dealing with a real device, and if it's
  57.        not there may crash the system.
  58.  
  59.    INPUTS
  60.        IORequest -- pointer to the IORequest struct that is to be aborted.
  61.  
  62.    RESULTS
  63.        io_Error -- is always set to IOERR_ABORT, even if the request
  64.                    finished successfully.
  65.  
  66.    SEE ALSO
  67.        ML_AbortIO, exec.library/SendIO, exec.library/CheckIO,
  68.        exec.libary/WaitIO
  69.  
  70.    BUGS
  71.        AbortIO() has very little information about the IO request and what
  72.        the handler task is doing with it.  It can check to see if the
  73.        IO request is queued, and if so, removes it.  However, if it's not
  74.        queued, all it can do is set the io_Error flag to IOERR_ABORTED and
  75.        hope the handler task realizes this before it's too late.  This is
  76.        why once the handler task has started servicing an IO request it must
  77.        finish it before it aborts it.
  78.  
  79. modemlink.device/CMD_CLEAR                          modemlink.device/CMD_CLEAR
  80.  
  81.  
  82.    NAME
  83.        Clear -- Clears all buffered incomming packets
  84.  
  85.    FUNCTION
  86.        This command will dispose any packets which have been internally
  87.        bufferd AND have not been used to satisfy a user read request
  88.        (CMD_READ or MLCMD_READ).
  89.  
  90.    IO REQUEST
  91.        io_Message      mn_ReplyPort initialized
  92.        io_Device       set by OpenDevice
  93.        io_Unit         set by OpenDevice
  94.        io_Command      CMD_CLEAR
  95.  
  96.    RESULTS
  97.        Error -- If the Clear succeeded, then io_Error will be null.  If the
  98.                 Clear failed, then the io_Error will be non-zero.  io_Error
  99.                 is used to indicate errors such as modem and handler task
  100.                 problems.
  101.  
  102.  
  103. modemlink.device/CMD_READ                            modemlink.device/CMD_READ
  104.  
  105.  
  106.    NAME
  107.        Read -- Read a packet's worth of data
  108.  
  109.    FUNCTION
  110.        This command is used to read a packet's worth of data.  A pointer to
  111.        the packet data is kept in io_Data, while the length of the data
  112.        is in io_Length.
  113.  
  114.        Notice that there is no actual LinkPkt being used.  The data is
  115.        stripped from the incomming packet and stored in the IOReq
  116.        structure.  Since the device will allocate the memory for the data,
  117.        it is important to deallocate the data (io_Data) once it is no longer
  118.        needed, as it won't do it for you.
  119.  
  120.        Before the program exits, be sure to AbortIO() then WaitIO() any
  121.        outstanding ioRequests.
  122.  
  123.    IO REQUEST
  124.        io_Message      mn_ReplyPort initialized
  125.        io_Device       set by OpenDevice
  126.        io_Unit         set by OpenDevice
  127.        io_Command      CMD_READ
  128.  
  129.    RESULTS
  130.        io_Length       number of bytes in block of data pointed to by
  131.                        io_Data
  132.        io_Data         pointer to block of data received
  133.  
  134.        Error -- If the Read succeded, then io_Error will be null.
  135.                 If the Read failed, then the io_Error will be non-zero.
  136.                 io_Error is used to indicate errors such as modem and
  137.                 handler task problems.
  138.  
  139. modemlink.device/CMD_WRITE                          modemlink.device/CMD_WRITE
  140.  
  141.  
  142.    NAME
  143.        Write -- Write a block of data as a single packet
  144.  
  145.    FUNCTION
  146.        This command causes a block of characters to be written out
  147.        as a single packet through the modem-link protocol.  If the
  148.        io_Length field is less then zero it will calculate the length
  149.        of the data block by counting all characters until it encounters
  150.        a NULL.
  151.  
  152.        The modem link protocol makes sure that the data sent is received
  153.        by the receiving end.  How this is determined is specific to the
  154.        protocol being used.  However, if an error (CRC32 check) does occur
  155.        it is up to the the protocol to make sure it resends the packet.
  156.        Only if a serious error (dropped carrier) occurs will the protocol
  157.        give up and abort the write request.
  158.  
  159.        The modem link handler task which manages out-going packets will not
  160.        reply the IO request until it is sure the receiving end has got it.
  161.        It is therefore recommended to use Asyncronous IO requests if high
  162.        speed communications are important.
  163.  
  164.    IO REQUEST
  165.        io_Message      mn_ReplyPort initialized
  166.        io_Device       set by OpenDevice
  167.        io_Unit         set by OpenDevice
  168.        io_Command      CMD_WRITE
  169.        io_Length       number of characters to be sent, or if set to
  170.                        -1 transmit until NULL encountered in Data
  171.        io_Data         pointer to block of data to transmit
  172.  
  173.    RESULTS
  174.        Error -- If the Write succeded, then io_Error will be null.
  175.                 If the Write failed, then the io_Error will be non-zero.
  176.                 io_Error is used to indicate errors such as modem and
  177.                 handler task problems.
  178.  
  179. modemlink.device/MLCMD_INIT                        modemlink.device/MLCMD_INIT
  180.  
  181.  
  182.    NAME
  183.        Init -- Initializes data in handler task
  184.  
  185.    FUNCTION
  186.        This command is used to pass important initialization data to the
  187.        handler task spawned by the device.  This includes a pointer to
  188.        an initialized IOExtSer structure, as well as the device base address
  189.        stored in io_Device.
  190.  
  191.        The handler task makes it's own private copies of the IOExtSer
  192.        struct, so it may be deallocated once it has been initialized.
  193.        However, the device/unit that was associated with that IOExtSer must
  194.        not be closed until after the handler task has been shut down.
  195.  
  196.    NOTE
  197.        The Init command must only be used just after the handler task has
  198.        been spawned, and this is usually done by the device itself.
  199.        Therefore this command should never be called by a user program as it
  200.        will have undefined results if not used properly.  The reason it's
  201.        documented here at all is for those who wish to write new handler tasks.
  202.        A new handler task implementing a new protocol can use this command to
  203.        receive important information about the serial device.
  204.  
  205.    IO REQUEST
  206.        io_Message      mn_ReplyPort initialized
  207.        io_Device       set by OpenDevice
  208.        io_Unit         set by OpenDevice
  209.        io_Command      MLCMD_INIT
  210.        io_Data         pointer to an initialized IOExtSer struct.
  211.  
  212.    RESULTS
  213.        Error -- If the Init succeded, then io_Error will be null.
  214.                 If the Init failed, then the io_Error will be non-zero.
  215.                 io_Error is used to indicate errors such as modem and
  216.                 handler task problems.
  217.  
  218. modemlink.device/MLCMD_QUERY                      modemlink.device/MLCMD_QUERY
  219.  
  220.  
  221.    NAME
  222.        Query -- ask the device for some very minor info about itself
  223.  
  224.    FUNCTION
  225.        This command is used to check to make sure the handler task is
  226.        still up and running.  It is possible that the handler task which
  227.        was spawned by the device has quit on it's own.  This can be caused
  228.        by loss of carrier or it received a shut down command from the remote
  229.        site.  A shut down command is automatically sent when the remote site
  230.        shuts down for any (system friendly) reason.
  231.  
  232.        This command may become more usefull later on...
  233.  
  234.    IO REQUEST
  235.        io_Message      mn_ReplyPort initialized
  236.        io_Device       set by OpenDevice
  237.        io_Unit         set by OpenDevice
  238.        io_Command      MLCMD_QUERY
  239.  
  240.    RESULTS
  241.        Error -- NULL if everything is fine, non-NULL otherwise.
  242.                 io_Error is used to indicate errors such as modem and
  243.                 handler task problems.
  244.  
  245. modemlink.device/MLCMD_READ                        modemlink.device/MLCMD_READ
  246.  
  247.  
  248.    NAME
  249.        Read -- Read a packet of data
  250.  
  251.    FUNCTION
  252.        This command will read a packet.  io_Data points to a LinkPkt
  253.        structure which contains all packet information.  io_Length is
  254.        not used, however the length of the data segment of the packet
  255.        is stored in the packet itself.  The LinkPkt fields that contain
  256.        useful information are:
  257.  
  258.          Length     -  size of data block
  259.          Socket     -  Socket (not really implemeted, set it to zero)
  260.          Data       -  a pointer to the data block
  261.          Flags      -  flags that affect the modem link protocol
  262.  
  263.        Once the packet returned by the MLCMD_READ command is no longer
  264.        needed it should be deallocated using FreePkt().  This is necessary
  265.        because the handler task allocates memory for each packet as it
  266.        comes in, and then it simply sends it to the user program when
  267.        satisfying a read request.  So, it is up the the user program
  268.        to free up all read packets, otherwise memory will be leaked.
  269.  
  270.    IO REQUEST
  271.        io_Message      mn_ReplyPort initialized
  272.        io_Device       set by OpenDevice
  273.        io_Unit         set by OpenDevice
  274.        io_Command      MLCMD_READ
  275.        io_Data         pointer to an initialized LinkPkt structure
  276.  
  277.    RESULTS
  278.        Error -- If the Read succeded, then io_Error will be null.
  279.                 If the Read failed, then the io_Error will be non-zero.
  280.                 io_Error is used to indicate errors such as modem and
  281.                 handler task problems.
  282.  
  283.  
  284. modemlink.device/MLCMD_WRITE                      modemlink.device/MLCMD_WRITE
  285.  
  286.  
  287.    NAME
  288.        Write -- Write a packet of data
  289.  
  290.    FUNCTION
  291.        This command will send a packet via the modem link protocol.
  292.        io_Data points to the LinkPkt struct that is to be transmitted.
  293.        It is important that all fields of the LinkPkt struct are
  294.        properly set.  The LinkPkt fields that are used by this command are:
  295.  
  296.          Length     -  size of data block
  297.          Socket     -  Socket (not really implemeted, set it to zero)
  298.          Data       -  a pointer to the data block
  299.          Flags      -  flags that affect the modem link protocol
  300.  
  301.        The modem link protocol makes sure that the data sent is received
  302.        by the receiving end.  How this is determined is specific to the
  303.        protocol being used.  However, if an error (CRC32 check) does occur
  304.        it is up to the the protocol to make sure it resends the packet.
  305.        Only if a serious error (dropped carrier) occurs will the handler
  306.        task give up and abort the write request.
  307.  
  308.        The modem link handler task which manages out-going packets will not
  309.        reply the IO request until it is sure the receiving end has got it.
  310.        It is therefore recommended to use Asyncronous IO requests if high
  311.        speed communications are important.
  312.  
  313.    IO REQUEST
  314.        io_Message      mn_ReplyPort initialized
  315.        io_Device       set by OpenDevice
  316.        io_Unit         set by OpenDevice
  317.        io_Command      MLCMD_WRITE
  318.        io_Data         pointer to a initialized LinkPkt structure
  319.  
  320.    RESULTS
  321.        Error -- If the Read succeded, then io_Error will be null.
  322.                 If the Read failed, then the io_Error will be non-zero.
  323.                 io_Error is used to indicate errors such as modem and
  324.                 handler task problems.
  325.  
  326.  
  327. modemlink.device/ML_AllocPkt                      modemlink.device/ML_AllocPkt
  328.  
  329.  
  330.    NAME
  331.        ML_AllocPkt -- Allocate memory for a single packet
  332.  
  333.    SYNOPSIS
  334.        Pkt = ML_AllocPkt()
  335.        D0
  336.  
  337.        struct LinkPkt *ML_AllocPkt( void );
  338.  
  339.    FUNCTION
  340.        This routine correctly allocates memory for a LinkPkt structure and
  341.        makes sure it is properly initialized.
  342.  
  343.    INPUTS
  344.        None
  345.  
  346.    RESULTS
  347.        Pkt - A pointer to the newly allocated LinkPkt structure.
  348.              If there wasn't enough free memory to allocate the packet,
  349.              then zero will be returned.  The pointer must always be
  350.              checked for NULL before use.
  351.  
  352.    WARNING
  353.        The result of any memory allocation MUST be checked, and a viable
  354.        error handling path taken.  ANY allocation may fail if memory has
  355.        been filled.
  356.  
  357.    NOTE
  358.       If the free list is corrupt, the system will panic with alert
  359.       AN_MemCorrupt, $01000005.
  360.  
  361.       This function may not be called from interrupts.
  362.  
  363.       A DOS process will have its pr_Result2 field set to
  364.       ERROR_NO_FREE_STORE if the memory allocation fails.
  365.  
  366.    SEE ALSO
  367.       exec.library/AllocMem, exec.library/FreeMem, FreePkt, FreePktList
  368.  
  369.    BUGS
  370.        None
  371.  
  372. modemlink.device/ML_AnswerTagList            modemlink.device/ML_AnswerTagList
  373.  
  374.  
  375.    NAME
  376.        ML_AnswerTagList -- Set modem to answer incomming call.
  377.        ML_AnswerTags -- Varargs stub for ML_AnswerTagList
  378.  
  379.    SYNOPSIS
  380.        result = ML_AnswerTagList( SerIO, tagList )
  381.        D0                         A0     A1
  382.  
  383.        ULONG ML_AnswerTagList( struct IOExtSer *, struct TagItem * );
  384.  
  385.        result = ML_AnswerTags( SerIO, Tag1, ... )
  386.  
  387.        ULONG ML_AnswerTags( struct IOExtSer *, ULONG, ... );
  388.  
  389.    FUNCTION
  390.        Sets the modem to auto-answer any incomming calls, and then waits
  391.        for a connection.  If the modem is not on, or does not respond to
  392.        the auto-answer command issued, it will drop out with an error.
  393.        As a safety measure it will only wait for a specified amount of
  394.        time.  If the modem does not answer an incomming call within that
  395.        specified amount of time it will timeout and return an error.
  396.  
  397.        For this routine to work it requires the serial device to be already
  398.        opened.  It will use the IOExtSer struct initialized by OpenDevice()
  399.        to communicate with the modem.
  400.  
  401.    NOTE
  402.        If the modem is already connected (ie: carrier detected) then it will
  403.        simply drop out and report modem has connected.
  404.  
  405.        It Requires a modem with auto-answer (all Hayes compatible modems
  406.        allow for auto-answer -- ATS0=1)
  407.  
  408.        Does not turn auto-answer off
  409.  
  410.    INPUTS
  411.        SerIO -- pointer to initialized IOExtSer structure (from OpenDevice)
  412.  
  413.        TagList -- (optional) pointer to (an array of) TagItem structures,
  414.             terminated by the value of TAG_END.  Here is a list of tag items
  415.             which may be used:
  416.  
  417.             ML_AnswerTime - sets the maximum time in seconds to wait for
  418.                  incomming call (default: 30).  ti_Data contains the new
  419.                  timeout amount.
  420.  
  421.             ML_Suffix - sets the new Suffix for all modem commands
  422.                  (default: "\r").  ti_Data points to an array of char.
  423.  
  424.             ML_OkText - defines the text the modem will use to indicate
  425.                  successful completion of command (default: "OK").
  426.                  ti_Data points to an array of char.
  427.  
  428.             ML_NoCarrierText - defines the text the modem will use to
  429.                  indicate there is no carrier (default: "NO CARRIER").
  430.                  ti_Data points to an array of char.
  431.  
  432.             ML_NoDialText - defines the text the modem will use to indicate
  433.                  there is no dial tone on the line (default: "NO DIALTONE").
  434.                  ti_Data points to an array of char.
  435.  
  436.             ML_AutoAnsText - sets the command to be used to set the modem
  437.                  into auto-answer mode (default: "ATS0=1").  ti_Data points
  438.                  to an array of char.
  439.  
  440.    RESULTS
  441.        result -- returns the result code returned by the modem.  See
  442.             ModemLink.h for a definition of all possible return codes.
  443.             Make sure to always check the result and plan for all
  444.             possible results.
  445.  
  446.    SEE ALSO
  447.        ML_DialTagList, ML_SendModemCmdTagList
  448.  
  449.    BUGS
  450.        None
  451.  
  452. modemlink.device/ML_DePacketizeData        modemlink.device/ML_DePacketizeData
  453.  
  454.  
  455.    NAME
  456.        ML_DePacketizeData -- Merge packets into one memory chunk
  457.  
  458.    SYNOPSIS
  459.        size = ML_DePacketizeData( PktList, Data, Length )
  460.        D0                         A0       A1    D0
  461.  
  462.        ULONG ML_DePacketizeData( struct MinList *, UBYTE, ULONG );
  463.  
  464.    FUNCTION
  465.        Will extract the data block from a list of LinkPkt structures and
  466.        merge them into a single memory chunk.  It requires a previously
  467.        allocated piece of memory to copy the data into.  The routine is
  468.        smart enough to not copy over more data then the Data buffer can
  469.        hold.  To calculate the correct size of this new memory block
  470.        make a call to ML_PacketDataSize().
  471.  
  472.        Be aware that it will NOT deallocate the LinkPkts or their data
  473.        blocks, so this may not be the most effecient method to do this.
  474.        Keep in mind that once the data blocks from a LinkPkt are no longer
  475.        needed, it's best to free the list of LinkPkt.  Therefore, a call to
  476.        ML_FreePktList() afterwards might be a good idea.
  477.  
  478.    INPUTS
  479.        PktList -- A linked list of LinkPkt structures
  480.  
  481.        Data -- A pointer to an allocated chunk of memory
  482.  
  483.        Length -- The size of the memory chunk to be written (Data)
  484.        
  485.    RESULTS
  486.        size -- the actual number of bytes copied.
  487.  
  488.    SEE
  489.        ML_FreePktList(), ML_PacketDataSize, ML_PacketizeData
  490.  
  491.    BUGS
  492.        None
  493.  
  494. modemlink.device/ML_DialTagList                modemlink.device/ML_DialTagList
  495.  
  496.  
  497.    NAME
  498.        ML_DialTagList -- Set modem to dial and connect with other modem
  499.        ML_DialTags -- Varargs stub for ML_DialTagList
  500.  
  501.    SYNOPSIS
  502.        result = ML_DialTagList( SerIO, PhoneNum, tagList )
  503.        D0                       A0     A1        A2
  504.  
  505.        ULONG ML_DialTagList( struct IOExtSer *, char *, struct TagItem * );
  506.  
  507.        result = ML_DialTags( SerIO, PhoneNum, Tag1, ... )
  508.  
  509.        ULONG ML_DialTags( struct IOExtSer *, char *, ULONG, ... );
  510.  
  511.    FUNCTION
  512.        Sets the modem to dial a given number and wait for a connection,
  513.        timeout or an error.  If the modem is not on, or does not respond to
  514.        the dial command issued, it will drop out with an error.  As a safety
  515.        measure it will only wait for a specified amount of time.  If the
  516.        modem does not connect within that specified amount of time it will
  517.        timeout and return an error.
  518.  
  519.        It is assumed that the phone number string contains a valid phone
  520.        number.  The phone number will be passed along to the modem.  However,
  521.        DialTagList() will prefix the phone number with the default dial
  522.        command ("ATDT "), unless it is over-riden by the ML_DialPrefix tag
  523.        (see below).  It will also append the default Suffix ("\r") to the
  524.        phone number string before it passes it to the modem, unless it to is
  525.        over-riden by the ML_Suffix tag (see below).  This means that there is
  526.        no need to include the modem dial command or carrige return codes in
  527.        the phone number string since DialTagList() adds them for you.
  528.  
  529.        For this routine to work it requires the serial device to be already
  530.        opened.  It will use the IOExtSer struct initialized by OpenDevice()
  531.        to communicate with the modem.
  532.  
  533.    INPUTS
  534.        SerIO -- pointer to initialized IOExtSer structure (from OpenDevice)
  535.  
  536.        PhoneNum -- number that will be dialed
  537.  
  538.        TagList -- (optional) pointer to (an array of) TagItem structures,
  539.             terminated by the value of TAG_END.  Here is a list of tag items
  540.             which may be used:
  541.  
  542.             ML_DialTime - sets the timeout in seconds for the dialer
  543.                  (Default: 45).  ti_Data contains the new timeout amount.
  544.  
  545.             ML_DialPrefix - sets the new dial prefix (defualt: "ATDT ").
  546.                  ti_Data points to an array of char.
  547.  
  548.             ML_Suffix - sets the new sufix string for all modem commands
  549.                  (default: "\r").  ti_Data points to an array of char.
  550.  
  551.             ML_OkText - defines the text the modem will use to indicate
  552.                  successful completion of command (default: "OK").
  553.                  ti_Data points to an array of char.
  554.  
  555.             ML_BusyText - defines the text the modem will use to indicate
  556.                  a busy signal (default: "BUSY").  ti_Data points to an
  557.                  array of char.
  558.  
  559.             ML_NoCarrierText - defines the text the modem will use to
  560.                  indicate there is no carrier (default: "NO CARRIER").
  561.                  ti_Data points to an array of char.
  562.  
  563.             ML_NoDialText - defines the text the modem will use to indicate
  564.                  there is no dial tone on the line (default: "NO DIALTONE").
  565.                  ti_Data points to an array of char.
  566.  
  567.    RESULTS
  568.        result -- returns the result code returned by the modem.  See
  569.             ModemLink.h for a definition of all possible return codes.
  570.             Make sure to always check the result and plan for all
  571.             possibilities.
  572.  
  573.    SEE ALSO
  574.        ML_AnswerTagList, ML_SendModemCmdTagList
  575.  
  576.    BUGS
  577.        None
  578.  
  579. modemlink.device/ML_EstablishTagList      modemlink.device/ML_EstablishTagList
  580.  
  581.  
  582.    NAME
  583.        ML_EstablishTagList -- establishes a protocol over a serial connection
  584.        ML_EstablishsTags -- Varargs stub for ML_EstablishTagList
  585.  
  586.    SYNOPSIS
  587.        result = ML_EstablishTagList( LinkIO, SerIO, tagList )
  588.        D0                            A0      A1     A2
  589.  
  590.        ULONG ML_EstablishTagList( struct IOExtLink *, IOExtSer *,
  591.             struct TagItem * );
  592.  
  593.        result = ML_EstablishsTags( LinkIO, SerIO, tagList )
  594.  
  595.        ULONG ML_EstablishTags( struct IOExtLink *, IOExtSer *,
  596.             struct TagItem * );
  597.  
  598.    FUNCTION
  599.        Will negotiate a ModemLink protocol across a serial connection.
  600.        This is done by polling the other side with an ENQ (char 0x05) and
  601.        then waiting for an ACK (char 0x06) from the remote side.  It will
  602.        return if one of the following occurs:
  603.  
  604.             1) a. It has sent an ENQ to the remote site AND
  605.                b. The remote site replied to the ENQ it has receive (ACK) AND
  606.                c. It has received an ENQ from the remote site AND
  607.                d. It has replied to the remote site's ENQ with an ACK
  608.  
  609.             OR
  610.  
  611.             2) Timeout.  Currently the timeout value is fixed at 5 seconds.
  612.             In the future there may be a tag item to allow for different
  613.             timeout values.
  614.  
  615.             OR
  616.  
  617.             3) It could not spawn the ModemLink handler task.  Low memory
  618.             situations may cause this.  Also, there may be another task with
  619.             the same name (it checks for this).
  620.  
  621.        If it successfully establishes the protocol, then communications
  622.        across the protocol may begin immediately.  If it can not connect
  623.        there is a problem; severe line noise may cause this routine to
  624.        timeout or think it has connected when it really hasn't.
  625.  
  626.        Despite the fact that this routine accepts tag items, there are no
  627.        tag items defined for it yet.  The tag items are only for future
  628.        expandibility.  The ModemLink device/lib may be expanded to support
  629.        multiple protocols through the tag items.  So, for now, make sure to
  630.        just pass TAG_END for future compatibility.
  631.  
  632.    INPUTS
  633.        LinkIO -- IOExtLink struct to be initialized.  If using .device make
  634.             sure it was initialized by OpenDevice() before hand.
  635.  
  636.        SerIO -- IOExtSer structure initialized by OpenDevice().  This will be
  637.             used to communicate with the serial.device.  NOTE: A copy of this
  638.             structre will be made and will be used by the ModemLink protocol.
  639.             It is therefore perfectly safe to free it's memory, but do NOT
  640.             close the serial.device until a call to ML_Terminate() is made.
  641.  
  642.        TagList -- no tag items defined; set to TAG_END.
  643.  
  644.    RESULTS
  645.        result -- code indicating success or failure.  Always check the result
  646.             code and plan for all possibilities.
  647.  
  648.    WARNING
  649.        Do NOT close the serial.device associated with SerIO until AFTER a
  650.        call to ML_Terminate().  This is because the ModemLink protocol will
  651.        make a copy of the SerIO structure and use the serial.device as if it
  652.        opened it itself.  So, keep the serial.device open and atleast one
  653.        copy (or the original) of SerIO until the ModemLink protocol is
  654.        properly terminated.  Then make a call to CloseDevice() using SerIO.
  655.  
  656.    BUGS
  657.  
  658.    SEE ALSO
  659.        ML_Terminate
  660.  
  661. modemlink.device/ML_FreePkt                        modemlink.device/ML_FreePkt
  662.  
  663.  
  664.    NAME
  665.        ML_FreePkt -- Deallocates memory for a single packet
  666.  
  667.    SYNOPSIS
  668.        ML_FreePkt( Pkt )
  669.                     A0
  670.  
  671.        void ML_FreePkt( struct LinkPkt * );
  672.  
  673.    FUNCTION
  674.        Deallocates all memory associated with a single packet.  This includes
  675.        the data block pointed to by Pkt->Data.
  676.  
  677.    INPUTS
  678.        Pkt -- pointer to LinkPkt struct to be deallocated
  679.  
  680.    RESULTS
  681.        None
  682.  
  683.    WARNING
  684.        Make sure the Length field of Pkt properly indicates the size of Data.
  685.        If there is no Data block then set Length and Data to NULL.
  686.  
  687.    BUGS
  688.        None
  689.  
  690. modemlink.device/ML_FreePktList                modemlink.device/ML_FreePktList
  691.  
  692.  
  693.    NAME
  694.        ML_FreePktList -- Deallocates a linked list of packets
  695.  
  696.    SYNOPSIS
  697.        ML_FreePktList( PktList )
  698.                        A0
  699.  
  700.        void ML_FreePktList( struct MinList * );
  701.  
  702.    FUNCTION
  703.        Will deallocate all packets in the link list.  This includes the data
  704.        block for each packet.
  705.  
  706.    INPUTS
  707.        PktList -- a linked list of packets
  708.  
  709.    RESULTS
  710.        None
  711.  
  712.    SEE ALSO
  713.        FreePkt
  714.  
  715.    BUGS
  716.        None
  717.  
  718. modemlink.device/ML_PacketDataSize          modemlink.device/ML_PacketDataSize
  719.  
  720.  
  721.    NAME
  722.        ML_PacketDataSize -- derives total amount of data in list of packcets
  723.  
  724.    SYNOPSIS
  725.        size = ML_PacketDataSize( PktList )
  726.        D0                        A0
  727.  
  728.        ULONG ML_PacketDataSize( struct MinList * );
  729.  
  730.    FUNCTION
  731.        Will scan through the linked list of packets and tally up the size
  732.        of all data blocks.  This does NOT include the size of the packet
  733.        structures themselves.  This can be very usefull when using
  734.        ML_DePacketizeData().
  735.  
  736.    INPUTS
  737.        PktList -- a linked list of packets
  738.  
  739.    RESULTS
  740.        size -- total amount of memory allocated to data blocks in the packets
  741.             making up the linked list.
  742.  
  743.    SEE ALSO
  744.        ML_DePacketizeData, ML_PacketizeData
  745.  
  746.    BUGS
  747.        None.
  748.  
  749. modemlink.device/ML_PacketizeData            modemlink.device/ML_PacketizeData
  750.  
  751.  
  752.    NAME
  753.        ML_PacketizeData -- split large memory chunk into multiple packets
  754.  
  755.    SYNOPSIS
  756.        result = ML_PacketizeData( PktList, Data, Length, PktSize )
  757.        D0                         A0       A1    D0      D1
  758.  
  759.        ULONG ML_PacketizeData( struct MinList *, UBYTE *, ULONG, ULONG );
  760.  
  761.    FUNCTION
  762.        Will split the memory chunk pointed to by Data into packets.  Each
  763.        packet allocated will have a Data block no greater then PktSize.  Be
  764.        aware that it may allocate a packet with a data block smaller then
  765.        PktSize.  This happens when PktSize doesn't evenly divide into Length.
  766.  
  767.        The packets it allocates will be inserted into a linked list.  The
  768.        MinList structure must be allocated and initialized, but does NOT need
  769.        to be empty.
  770.  
  771.        It will not deallocate the memory chunk, but it is safe to deallocate
  772.        the memory chunk immediatly afterwards.  Note that since it basically
  773.        makes a second copy of the memory chunk, this can be very memory
  774.        wastefull.  For large chunks it may be best to manually create packets
  775.        who's Data pointers point to different positions in the large memory
  776.        chunk.
  777.  
  778.        If it can't find enough memory to allocate all packets it will
  779.        deallocate all packets successfully allocated and return an error.
  780.  
  781.    INPUTS
  782.        PktList -- MinList struct initialized by NewList()
  783.  
  784.        Data -- pointer to memory chunk
  785.  
  786.        Length -- size of memory chunk (Data)
  787.  
  788.        PktSize -- maximum size of each packet created
  789.  
  790.    RESULTS
  791.        result -- Zero if successful, non-zero otherwise.
  792.  
  793.    SEE ALSO
  794.        amiga.lib/NewList
  795.  
  796.    BUGS
  797.        None
  798.  
  799. modemlink.device/ML_SendModemCMDTagList             .../ML_SendModemCMDTagList
  800.  
  801.  
  802.    NAME
  803.        ML_SendModemCMDTagList -- Send raw command to modem
  804.        ML_SendModemCMDTags -- Varargs stub for ML_SendModemCMDTagList
  805.  
  806.    SYNOPSIS
  807.        result = ML_SendModemCMDTagList( SerIO, CMD, tagList )
  808.        D0                               A0     A1   A2
  809.  
  810.        ULONG ML_SendModemCMDTaglist( struct IOExtSer *, char *,
  811.             struct TagItem * );
  812.  
  813.        result = ML_SendModemCMDTags( SerIO, CMD, tag1, ... )
  814.  
  815.        ULONG ML_SendModemCMDTags( struct IOExtSer *, char *, ULONG, ... );
  816.  
  817.    FUNCTION
  818.        This is a general purpose routine designed to issue any modem command.
  819.        Once the modem command is issued it will wait for a response from the
  820.        modem.  Valid responses are standard result codes from the modem, PLUS
  821.        it will check for carrier detect.  Therefore, if the carrier is
  822.        detected, this routine will return a result code indicating that.
  823.  
  824.        It is assumed that the command string is a valid modem command.
  825.        The modem command string (CMD) is passed along to the modem.  However,
  826.        SendModemCMD() will append the default Suffix ("\r") to the command
  827.        string before it passes it to the modem, unless it is over-riden by
  828.        the ML_Suffix tag (see below).  This means that there is no need to
  829.        include carrige return codes in the command being issued, since
  830.        SendModemCMD() appends it for you.  To issue a command so that the
  831.        Suffix is NOT appened to the command use the ML_Suffix tag and set it
  832.        to NULL.
  833.  
  834.        For this routine to work it requires the serial device to be already
  835.        opened.  It will use the IOExtSer struct initialized by OpenDevice()
  836.        to communicate with the modem.
  837.  
  838.    INPUTS
  839.        SerIO -- pointer to initialized IOExtSer structure (from OpenDevice)
  840.  
  841.        CMD -- pointer to a string containing modem command to issue
  842.  
  843.        tagList -- (optional) pointer to (an array of) TagItem structures,
  844.             terminated by the value of TAG_END.  Here is a list of tag items
  845.             which may be used:
  846.  
  847.             ML_DialTime - sets the timeout in seconds for ANY modem command
  848.                  issued, not just dial commands (Default: 45).  ti_Data
  849.                  contains the new timeout amount.
  850.  
  851.             ML_Suffix - sets the new Suffix for all modem commands
  852.                  (default: "\r").  ti_Data points to an array of char.
  853.  
  854.             ML_OkText - defines the text the modem will use to indicate
  855.                  successful completion of command (default: "OK").
  856.                  ti_Data points to an array of char.
  857.  
  858.             ML_BusyText - defines the text the modem will use to indicate
  859.                  a busy signal (default: "BUSY").  ti_Data points to an
  860.                  array of char.
  861.  
  862.             ML_NoCarrierText - defines the text the modem will use to
  863.                  indicate there is no carrier (default: "NO CARRIER").
  864.                  ti_Data points to an array of char.
  865.  
  866.             ML_NoDialText - defines the text the modem will use to indicate
  867.                  there is no dial tone on the line (default: "NO DIALTONE").
  868.                  ti_Data points to an array of char.
  869.  
  870.    RESULTS
  871.        result -- returns the result code returned by the modem.  See
  872.             ModemLink.h for a definition of all possible return codes.
  873.             Make sure to always check the result and plan for all
  874.             possibilities.
  875.  
  876.    SEE ALSO
  877.        ML_DialTagList, ML_AnswerTagList
  878.  
  879.    BUGS
  880.        None
  881.  
  882. modemlink.device/ML_Terminate                    modemlink.device/ML_Terminate
  883.  
  884.  
  885.    NAME
  886.        ML_Terminate -- terminate ModemLink protocol
  887.  
  888.    SYNOPSIS
  889.        ML_Terminate( LinkIO )
  890.                      A0
  891.  
  892.        void ML_Terminate( struct IOExtLink * );
  893.  
  894.    FUNCTION
  895.        This will shut down the ModemLink handler task, which in effect shuts
  896.        down the ModemLink protocol.  Any outstanding IO requests will be
  897.        aborted.  Any new IO requests will fail.  To re-establish the
  898.        ModemLink protocol use ML_EstablishTagList().
  899.  
  900.    NOTE
  901.        Before the handler task exits, it sends a kill command to the remote
  902.        site.  This of course shuts down the remote site as well.  This means
  903.        that the handler task may shut down on you without warning if it gets
  904.        a kill signal from the remote site.  Always check the io_Error field
  905.        of every completed IO request.  If the handler task has shut down all
  906.        IO requests will fail with an error code of LinkErr_NOPROC.
  907.  
  908.    INPUTS
  909.        LinkIO -- pointer to a LinkIO request structure (initialized by
  910.             ML_EstablishTagList)
  911.  
  912.    RESULTS
  913.  
  914.    BUGS
  915.  
  916.    SEE ALSO
  917.        ML_EstablishTagList
  918.  
  919.  
  920. modemlink.lib/ML_AbortIO (lib)                        modemlink.lib/ML_AbortIO
  921.  
  922.  
  923.    NAME
  924.        ML_AbortIO -- abort ModemLink.lib I/O command
  925.  
  926.    SYNOPSIS
  927.        ML_AbortIO( IOReq )
  928.        void ML_AbortIO( struct IORequest * );
  929.  
  930.    FUNCTION
  931.        This is identical to what ModemLink.device/AbortIO() does.  This
  932.        routine must be used when linking with ModemLink.lib.
  933.        ModemLink.device/AbortIO() will not work, and may crash the system
  934.        when linking with ModemLink.lib.  If using the ModemLink.device, make
  935.        the exec.library call to AbortIO() instead.
  936.  
  937.       This function attempts to abort a specified read or write request.
  938.       If the request being aborted is a WRITE request and is currently
  939.       active, the IO request will NOT be aborted and will be completed
  940.       as normal.  If the request is queued, it is painlessly removed.
  941.       The request will be returned in the same way any completed request
  942.       is.
  943.  
  944.       After AbortIO(), you must generally do a WaitIO().
  945.  
  946.    INPUTS
  947.        IOReq - pointer to a ModemLink IOReq structure
  948.  
  949.    RESULTS
  950.        error - a sign-extended copy of the io_Error field of the IOReq.
  951.             Make sure to always check the error returned.
  952.  
  953.    SEE ALSO
  954.        ML_SendIO, ModemLink.device/AbortIO, exec.library/CheckIO,
  955.        exec.library/WaitIO
  956.  
  957.    BUGS
  958.        AbortIO() has very little information about the IO request and what
  959.        the handler task is doing with it.  It can check to see if the
  960.        IO request is queued, and if so, removes it.  However, if it's not
  961.        queued, all it can do is set the io_Error flag to IOERR_ABORTED and
  962.        hope the handler task realizes this before it's too late.  This is
  963.        why once the handler task has started servicing an IO request it must
  964.        finish it before it aborts it.
  965.  
  966. modemlink.lib/ML_DoIO (lib)                              modemlink.lib/ML_DoIO
  967.  
  968.  
  969.    NAME
  970.        ML_DoIO -- perform ModemLink.lib I/O command and wait for completion
  971.  
  972.    SYNOPSIS
  973.        error = ML_DoIO( IOReq )
  974.        BYTE ML_DoIO( struct IORequest * );
  975.  
  976.    FUNCTION
  977.        This routine is intended only to be used when using ModemLink.lib
  978.        (linked at compile time) and is NOT available in the
  979.        ModemLink.device (link at run time -- use exec.library DoIO routine
  980.        for that).  It's only purpose is to provide an API similar to that of
  981.        exec's device IO routine; DoIO.  Therefore, this routine can only be
  982.        used to send ModemLink IO requests when linking with ModemLink.lib at
  983.        compile time.
  984.  
  985.    INPUTS
  986.        IOReq - pointer to a ModemLink IOReq structure
  987.  
  988.    RESULTS
  989.        error - a sign-extended copy of the io_Error field of the IOReq.
  990.             Make sure to always check the error returned.
  991.  
  992.    SEE ALSO
  993.        ML_SendIO, exec.library/AbortIO, exec.library/DoIO,
  994.        exec.library/CheckIO, exec.library/WaitIO, exec.library/SendIO
  995.  
  996.    BUGS
  997.        None
  998.  
  999. modemlink.lib/ML_SendIO (lib)                          modemlink.lib/ML_SendIO
  1000.  
  1001.  
  1002.    NAME
  1003.        ML_SendIO -- initiate a ModemLink.lib I/O command
  1004.  
  1005.    SYNOPSIS
  1006.        ML_SendIO( IOReq )
  1007.  
  1008.        void ML_SendIO( struct IORequest * );
  1009.  
  1010.    FUNCTION
  1011.        This routine is intended only to be used when using ModemLink.lib
  1012.        (linked at compile time) and is NOT available in the
  1013.        ModemLink.device (link at run time -- use exec.library SendIO routine
  1014.        for that).  It's only purpose is to provide an API similar to that of
  1015.        exec's device IO routine; SendIO.  Therefore, this routine can only be
  1016.        used to send ModemLink IO requests when linking with ModemLink.lib at
  1017.        compile time.
  1018.  
  1019.        This will make an asyncronous request to the ModemLink.lib to be
  1020.        processed.  Control will be returned immediately without waiting for
  1021.        the command to complete.
  1022.  
  1023.        Remember that ModemLink.lib is designed to act like a device, so
  1024.        ML_SendIO is indeed an asyncronous call just like the corresponding
  1025.        exec routine, SendIO.  Therefore, you may use exec's CheckIO() and
  1026.        WaitIO() on a dispatched IO request.  To abort a request you MUST use
  1027.        ML_AbortIO() instead of exec's AbortIO().
  1028.  
  1029.        The io_Flags field of the IOReq will be set to zero before the request
  1030.        is sent.  See SendIO() in the Amiga RKM Includes and Autodocs for more
  1031.        details.
  1032.  
  1033.    INPUTS
  1034.        IOReq -- pointer to an initialized IOExtLink structure
  1035.  
  1036.    RESULTS
  1037.        None
  1038.  
  1039.    SEE ALSO
  1040.        ML_DoIO, ML_AbortIO, exec.library/DoIO, exec.library/SendIO,
  1041.        exec.library/CheckIO, exec.library/WaitIO
  1042.  
  1043.    BUGS
  1044.        None
  1045.